/**
 *
 * The MIT License
 *
 * Copyright (c) 2008 Board of Trustees, Leland Stanford Jr. University. All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:

 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package org.macdadi.core.client.auth;

import com.google.gwt.user.client.rpc.AsyncCallback;

/**
 * @author Ben Suter <ben.suter@gmail.com>
 */
public interface AuthServiceAsync
{

    /**
     * Authenticate a user. If the authentication succeeds, either
     * a new session is established, or an existing session is
     * extended.
     *
     * @param email    identifies the user (case-sensitive)
     * @param password authenticates the user (case-sensitive)
     * @return true if the credentials are valid
     */
    void login(String email, String password, AsyncCallback async);

    /**
     * Terminate the specified user's session. The user must be
     * currently authenticated for this method to succeed.
     *
     * @param user a user with a current session
     * @return true if no session remains for this user
     */
    void logout(AuthenticatedUser user, AsyncCallback async);

    /**
     * Find the authenticated user for the specified session.
     * If the session is not valid, or if no such session exists,
     * null is returned.
     *
     * @param   email       the email (username) of the user
     * @param   authToken   a current session identifier
     * @return              null if session invalid or non-existent, otherwise an authenticated user
     */
    void getUserForSession(String email, String authToken, AsyncCallback async);

    /**
     * Determines whether the user authenticated with <code>authToken</code
     * is permitted to view domain for the specified project. Generally the
     * result is true if the project is public or the user is an active
     * member of the project.
     *
     * @param authToken token identifying an authenticated user
     * @param projectId the project in question
     * @return true if the user may view domain for the project
     */
    void isAuthorizedProjectRead(String authToken, int projectId, AsyncCallback async);

    /**
     * Determine whether the user authenticated with <code>authToken</code>
     * has permission to perform <code>operation</code> against <code>target</code>
     * for the specified project. This method is intended for use by client-side code
     * that exposes editing controls only to users who are permitted to perform such
     * modifications.
     * <p/>
     * To check whether the current user is permitted to modify a goal, the call
     * would look something like this:
     * <code>isAuthorizedOperation(currentAuthToken, currentProjectId, TARGET_GOALS, OPERATION_EDIT);</code>
     * <p/>
     * Implementation note: This method invokes the <code>auth_check_operation</code>
     * stored procedure, which is used internally by other stored procedures to
     * check the role-based permissions for any modifications to domain.
     *
     * @param authToken token identifying an authenticated user
     * @param projectId identifies the project
     * @param target    a domain collection, one of the TARGET_XXX constants
     * @param operation the type of modification, one of the OPERATION_XXX constants
     * @return true if the user may perform the modification
     */
    void isAuthorizedOperation(String authToken, int projectId, String target, String operation, AsyncCallback async);
}
